home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_100 / 134_01 / cprofile.nro < prev    next >
Encoding:
Text File  |  1985-08-19  |  2.8 KB  |  81 lines
  1. .so AN.NRO
  2. .TH CPROFILE 1 "BDS 'C' profiler"
  3. .SH NAME
  4. CPROFILE - BDS 'C' profiler
  5. .SH SYNOPSIS
  6. .bo
  7. cprofile <target command> : <options> [>outfile]
  8. .sp
  9. Options:
  10. .sp
  11. .in +5
  12. -SourceFiles file1 file2 ...
  13. .br
  14. -LineCount <n>
  15. .br
  16. -PageLength <n>
  17. .sp
  18. .in -5
  19. .SH DESCRIPTION
  20. .PP
  21. CPROFILE is a "profiler" for BDS 'C' programs.  It runs a user program (the
  22. "target command" in the synopsis) and counts the number of times that each
  23. source statement was executed.
  24. .PP
  25. To operate correctly, the target program must have been compiled with the '-k'
  26. option (which enables the Kirkland debugger) and linked with the '-d' option
  27. (which places restart instructions at the head of functions).  In addition,
  28. the '-ns' (no system libraries) option is recommended, so that counts are
  29. obtained for calls to system functions.
  30. .PP
  31. The output from CPROFILE is an annotated source listing of the original source
  32. program.  In the left margin appear the number of times each source statement
  33. was executed.  This information is useful for performance analysis (where is
  34. a program spending its time?), for debugging (did the program get to this
  35. code?) and for testing (has all code been exercised?).
  36. .PP
  37. Several options are available to CPROFILE.  CPROFILE options appear after the
  38. target program's options, separated from it by a colon.  Note that spaces
  39. are required before and after the colon.
  40. .PP
  41. -PageLength sets the number of lines per page on the output listing.  Default
  42. is 58.
  43. .PP
  44. -LineCount sets the number of distinct source statements that are expected in
  45. the program.  Each source statement requires a six-byte table entry at run
  46. time.  Default is 500, allowing programs of up to about 500 lines to be
  47. analyzed.
  48. .PP
  49. -SourceFiles is intended for use when several program or library source files
  50. have been linked into the program.  If multiple source programs have been
  51. supplied, they must be specified here
  52. .ul
  53. in the same order as they were supplied to L2.
  54. Default is <program>.C, where <program> is the name of the target command.
  55. .SH EXAMPLES
  56. .bo
  57. .in +5
  58. .ti -5
  59. cprofile ctoa mylib.c >mylib.csm : -lc 2000 -sf ctoa.c ctoa2.c >ctoa.prf
  60. .sp
  61. .ti -5
  62. cprofile myprog myfile : -pl 80
  63. .sp
  64. .in -5
  65. .SH DIAGNOSTICS
  66. .sp
  67. "Command must be supplied."
  68. .PP
  69. No <target command> was supplied on the CPROFILE command line.  The correct
  70. sequence is: CPROFILE <command> <options> : <CPROFILE-options>.
  71. .sp
  72. "Profile table is full; abandoning program."
  73. .PP
  74. The program had too many source statements to analyze with the current value
  75. of -LineCount.  Rerun with a larger '-lc' option.
  76. .sp
  77. "Profile table overlays the profiler."
  78. .PP
  79. Available memory on the system is not sufficient to run CPROFILE with the
  80. requested '-lc' option.  Use a smaller '-lc'.
  81. ed for use when several